From 635df85f70d6f1a907ed3112c43bcfd74166e045 Mon Sep 17 00:00:00 2001
From: Alexandre Emsenhuber <ialex.wiki@gmail.com>
Date: Sat, 11 Aug 2012 22:48:09 +0200
Subject: [PATCH] Improve documentation of maintenance scripts.

Change-Id: I29dd0d4d18ea3d1b9795fac2f0b74b04ef2d955a
---
 maintenance/refreshLinks.php    |  6 ++++++
 maintenance/renameDbPrefix.php  |  7 +++++++
 maintenance/renderDump.php      |  6 ++++++
 maintenance/resetUserTokens.php | 25 +++++++++++++++----------
 maintenance/rollbackEdits.php   |  7 +++++++
 maintenance/runBatchedQuery.php |  6 ++++++
 maintenance/runJobs.php         | 10 ++++++++--
 7 files changed, 55 insertions(+), 12 deletions(-)

diff --git a/maintenance/refreshLinks.php b/maintenance/refreshLinks.php
index b5aa85f891..699d88552e 100644
--- a/maintenance/refreshLinks.php
+++ b/maintenance/refreshLinks.php
@@ -17,11 +17,17 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup Maintenance
  */
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script to refresh link tables.
+ *
+ * @ingroup Maintenance
+ */
 class RefreshLinks extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/renameDbPrefix.php b/maintenance/renameDbPrefix.php
index 289e747f44..d8e53eedd0 100644
--- a/maintenance/renameDbPrefix.php
+++ b/maintenance/renameDbPrefix.php
@@ -1,5 +1,6 @@
 <?php
 /**
+ * Change the prefix of database tables.
  * Run this script to after changing $wgDBprefix on a wiki.
  * The wiki will have to get downtime to do this correctly.
  *
@@ -18,11 +19,17 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup Maintenance
  */
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script that changes the prefix of database tables.
+ *
+ * @ingroup Maintenance
+ */
 class RenameDbPrefix extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/renderDump.php b/maintenance/renderDump.php
index 78c5b6f31e..c76a89b499 100644
--- a/maintenance/renderDump.php
+++ b/maintenance/renderDump.php
@@ -30,6 +30,12 @@
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script that takes page text out of an XML dump file
+ * and render basic HTML out to files.
+ *
+ * @ingroup Maintenance
+ */
 class DumpRenderer extends Maintenance {
 
 	private $count = 0;
diff --git a/maintenance/resetUserTokens.php b/maintenance/resetUserTokens.php
index a1c4eaeb59..ef8f5b0ebd 100644
--- a/maintenance/resetUserTokens.php
+++ b/maintenance/resetUserTokens.php
@@ -1,7 +1,7 @@
 <?php
 /**
- * Script to reset the user_token for all users on the wiki. Useful if you
- * believe that your user table was acidentally leaked to an external source.
+ * Reset the user_token for all users on the wiki. Useful if you believe
+ * that your user table was acidentally leaked to an external source.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -25,6 +25,11 @@
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script to reset the user_token for all users on the wiki.
+ *
+ * @ingroup Maintenance
+ */
 class ResetUserTokens extends Maintenance {
 	public function __construct() {
 		parent::__construct();
@@ -33,7 +38,7 @@ class ResetUserTokens extends Maintenance {
 	}
 
 	public function execute() {
-		
+
 		if ( !$this->getOption( 'nowarn' ) ) {
 			$this->output( "The script is about to reset the user_token for ALL USERS in the database.\n" );
 			$this->output( "This may log some of them out and is not necessary unless you believe your\n" );
@@ -42,7 +47,7 @@ class ResetUserTokens extends Maintenance {
 			$this->output( "Abort with control-c in the next five seconds (skip this countdown with --nowarn) ... " );
 			wfCountDown( 5 );
 		}
-		
+
 		// We list user by user_id from one of the slave database
 		$dbr = wfGetDB( DB_SLAVE );
 		$result = $dbr->select( 'user',
@@ -53,19 +58,19 @@ class ResetUserTokens extends Maintenance {
 
 		foreach ( $result as $id ) {
 			$user = User::newFromId( $id->user_id );
-			
+
 			$username = $user->getName();
-			
+
 			$this->output( "Resetting user_token for $username: " );
-			
+
 			// Change value
 			$user->setToken();
 			$user->saveSettings();
-			
+
 			$this->output( " OK\n" );
-			
+
 		}
-		
+
 	}
 }
 
diff --git a/maintenance/rollbackEdits.php b/maintenance/rollbackEdits.php
index 3e57e01fbf..c9f607edc3 100644
--- a/maintenance/rollbackEdits.php
+++ b/maintenance/rollbackEdits.php
@@ -18,11 +18,18 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup Maintenance
  */
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script to rollback all edits by a given user or IP provided
+ * they're the most recent edit.
+ *
+ * @ingroup Maintenance
+ */
 class RollbackEdits extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/runBatchedQuery.php b/maintenance/runBatchedQuery.php
index 83e0cab856..6322d31de3 100644
--- a/maintenance/runBatchedQuery.php
+++ b/maintenance/runBatchedQuery.php
@@ -19,11 +19,17 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup Maintenance
  */
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script to run a database query in batches and wait for slaves.
+ *
+ * @ingroup Maintenance
+ */
 class BatchedQueryRunner extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/runJobs.php b/maintenance/runJobs.php
index fdc141bb3b..af7c906cc3 100644
--- a/maintenance/runJobs.php
+++ b/maintenance/runJobs.php
@@ -1,8 +1,8 @@
 <?php
 /**
- * This script starts pending jobs.
+ * Run pending jobs.
  *
- * Usage:
+ * Options:
  *  --maxjobs <num> (default 10000)
  *  --type <job_cmd>
  *
@@ -21,11 +21,17 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup Maintenance
  */
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script that runs pending jobs.
+ *
+ * @ingroup Maintenance
+ */
 class RunJobs extends Maintenance {
 	public function __construct() {
 		parent::__construct();
-- 
2.20.1